//
//  SFCAPRPool.h
//  SVNForCocoa
//
//  Created by Jeremy Pereira on 06/11/2013.
//  Copyright (c) 2013 Jeremy Pereira. All rights reserved.
//

#import <Foundation/Foundation.h>
#import "SFCObject.h"
/*!
 *    @file
 *    @brief Wraps an APR pool as an Objective-C object
 */

/*!
 *    @brief Wraps an APR pool as an Objective-C object.
 *
 *    The Objective-C object mirrors the underlying apr pools so parent objects
 *    maintain a strong reference to their children.
 *
 *    The underlying APR pool is created with the object and is destroyed when
 *    the object is deallocated, if it has not already been done.  As clearing 
 *    or destroying a parent pool also destroys its children, it is
 *    possible that the object may not contain a valid apr_pool_t. To avoid this
 *    avoid taking strong references to APR pools.  Thus ARC will nill out the 
 *    obvjects because they will be deallocated by the clear of their parent.
 */
@interface SFCAPRPool : SFCObject

/*!
 *    @brief Make a new APR pool object
 *
 *    The APR pool is created and wrapped with an Obj-C object.  It's parent 
 *    is set to the APR pool of the passed in parent.
 *
 *    @param parent Parent SFCAPRPool for the new object.  If nil, creates a 
 *                  root pool.
 *    @param error  If non nil and there is an error, this wil be filled in.
 *
 *    @return The new pool or nil if we fail to create the pool.
 */
+(SFCAPRPool*) makePoolWithParent: (SFCAPRPool*) parent
                            error: (NSError* __autoreleasing*) error;

/*!
 *    @brief The parent pool of this pool.
 */
@property (nonatomic, readonly, weak) SFCAPRPool* parent;

/*!
 *    @brief True if the underlying APR pool is still valid.
 */
@property (nonatomic, readonly, assign) bool isAlive;

/*!
 *    @brief Test for whether a particular sub pool is a direct child of this 
 *           pool.
 *
 *    Grand children and their descendents do not count.
 *
 *    @param aPool Pool to test for.
 *
 *    @return true if the pool is a direct child of this pool.
 */
-(bool) hasChild: (SFCAPRPool*) aPool;

/*!
 *    @brief Clears the pool of all allocations and destoys all subpools.
 */
-(void) clear;

/*!
 *    @brief Destroy the APR pool,
 *
 *    Destroys the APR pool associated with this object.  It also removes this
 *    pool from its parent pool.
 */
-(void) destroy;

/*!
 *    @brief Add a child to theis pool.
 *
 *    @param newChild The child to add.
 */
-(void) addChild: (SFCAPRPool*) newChild;

/*!
 *    @brief Removes the given child.
 *
 *    If the child is not a child of this pool, it is ignored.
 *
 *    @param childToGo Child to remove.
 */
-(void) removeChild: (SFCAPRPool*) childToGo;

/*!
 *    @brief Adds and returns a new child pool to the receiver.
 *
 *    @return A new child pool.
 */
-(SFCAPRPool*) newChild;

@end
